= OnTime Rewards =
==Automated Rewards==
With this component of the// OnTime// plugin the server administrator can establish a system of rewards.  Rewards can be issued in several ways:
* A one time event:  Automatically issued when a player has been on the server for a specified amount of time.
* A recurring event for a limited time frame:  Automatically issued when a player has been on the server for a specified time, repeating at a specified interval until the next defined reward's time is achieved.
* A perpetual event which is issued forever: Automatically issued when a player has been on the server for a specified time, repeating at a specified interval, continuing forever.
* A one time event for a specified player, but issued at an optional time in the future. (See 'individual' rewards below for details.)
* As a reward for referring another player, but only after that player has been on the server for the specified amount of time.
* A daily, weekly, or monthly reward issued to the 'top players' with the most "OnTime" overall, for the previous day, previous week, and/or previous month.
\\
\\
Most rewards are defined to be issued at a time specified in number of days, hours, and minutes, and can be one of six types of rewards: 
*an economy amount to be put into the player's account
*a quantity of an MineCraft item to be added to a player's inventory
*a change to a specified 'group' defined via a permissions plugin
*a permission to be added to the player's permission list
*a command to be executed
*an amount of XP to be awarded.
\\
\\
When a player logs into the system the next automated //OnTime Reward// for which the player is eligible will be determined, and a system event will be scheduled to issue that reward at the right time.  If a player quits or is kicked before their next reward time is reached, the reward event will be automatically cancelled.
\\
\\
If enabled, //OnTime// will determine when a player is Away From Keyboard (AFK) and will not include AFK time in //Total OnTime// nor will it be applied toward rewards.  While AFK a player will never receive any rewards.
\\
\\
== Individual or 'Indi' Rewards ==
An individual reward is a single occurrence award that is only given to a single, specified player.  The rewards that can be issued are the same as those that are automated, in fact the administrator can select one of the automated rewards and issue the specified user the reward at almost any time.  A reward once added to the list can also be identified as an 'individual only' reward such that it is never issued automatically.  Individual rewards are one time only so even if the reward 'set' is a recurring reward, the set instance will not repeat.

\\
When an individual reward is specified for a player, the admin has several options to determine when the reward will be issued.
* Delta - A 'delta' time setting will issue the reward when the specified player has be on the server that much time longer then their current //Total Ontime//.
* Login - A 'login' setting will issue the reward the next time the player logs onto the server.  (No time stamp is specified with this option.)  If the player is online at the time the reward is setup, they will have to logoff and then log back on to receive the reward.
* OnTime - An 'ontime' setting will issue the reward when the specified player's //Total OnTime// reaches that value.  This is the setting most similar to the Automated rewards.
* Real - A 'real' setting will issue the reward according to the server, or 'real' time.  Similar to the 'delta' setting this is an amount of time that must pass before the reward is issued.  The 'clock' will be ticking for this reward regardless if the player is on or not.  If the player is offline when the timer expires the reward will be issued when the user next logs on.
\\

For example, using a pre-set list of OnTime Rewards:


>\ontime rewards list

21:29:30 [INFO] #1 Time: 2 Day 0 Hr 2 Min  Reward: 1 of DIAMOND

21:29:30 [INFO]  Recurr: 0 Day 4 Hr 0 Min

21:29:30 [INFO] #2 Time: 5 Day 0 Hr 0 Min  Reward: 100 coins

21:29:30 [INFO]  Recurr: 0 Day 4 Hr 0 Min

21:29:30 [INFO] #3 Time: 6 Day 0 Hr 0 Min  Reward: 5 of COAL

21:29:30 [INFO] #4 Time: 10 Day 0 Hr 0 Min  Reward: 100 XP

21:29:30 [INFO]  Recurr: 0 Day 4 Hr 0 Min

21:29:30 [INFO] #5 Time:  (Individual)      Reward: 100 coins

>
*> ontime rewards set edge209 delta 4 0 1 0
> This command will create a single occurrence of the Reward #4 to happen for edge209 in 0 days 1 hour 0 minutes of additional time on the server.  This player and all other players will still receive the same reward #4 when they get to 10 days on the server.

*> ontime rewards set edge209 real 0 5 0
> This command will create a single reward for edge209, which will happen 5 hours of real (server) time in the future, regardless of Edge209's amount of OnTime.  Only rewards 'set' in this manner can deliver a reward #5, as this reward will be give automatically.

The following command is what makes a reward an 'individual reward' only.
*> ontime rewards indi <rewardID>
== Exclusive Rewards ==

'Exclusive' rewards are controlled via group-based permissions, and //OnTime// is compatible with a large number of 'permissions' plugins with [[http://dev.bukkit.org/server-mods/vault/|Vault ]].  When a reward is defined as //exclusive//, a permission sting is automatically generated, which can be used in the permission plugin's config files or commands.  
\\
\\
The command string will be of the format: 'ontime.reward.<rewardTag>'.  <rewardTag> is auto-generated by OnTime and can be found in the 'rewards.yml' file, or displayed using the /ontime rewards info <rewardID/[ALL]>
\\

To make management easier, the applicable groups can be listed in the //OnTime// command which sets the 'exclusive' mode, and //OnTime// will update the permissions config files directly. 
> (ex: "/ontime rewards exclusive add 1 builder", where "1" is the exclusive reward's rewardID, and 'builder' is the permission group to have access to reward #1)
\\
After //exclusive// rewards are defined, only members of groups which have the associated permissions string for a reward, will receive that reward.  For all other players, who don't have the right permission, the //exclusive// rewards will be skipped.
\\
\\
To see the reward's permission string as well as the groups which have this permission the following command can be used:
\\
"/ontime rewards info <rewardID>".  <rewardID> is the reward list order seen with '/ontime rewards list'
\\
\\
=='Referred By' Rewards==
Player's can receive reward(s) for referring other players to your server.  (Please see the [[http://dev.bukkit.org/server-mods/ontime/pages/referred-by-rewards/|//'Referred By'//]] page for more details on how to use this feature.)
To define a reward as a 'referred by' reward, the following command must be executed:
>/ontime reward refer <rewardID>, where <rewardID> is the reward numbers shown in the  // /ontime reward list // command.
\\
The 'start time' specified is the amount of time the referred player must play on the server //(Total OnTime)// before the referring player receives the reward.  'Referred by' rewards will never be awarded automatically, and will only be used as referral rewards.
\\
\\
=='Top Player' Rewards
The players on your server which log the most playtime for a given day, week, month, and/or total, can be rewarded for their dedication.  At the start of each new day, OnTime will look for any 'top' rewards and issue them as appropriate per the configuration.  If Reports are enabled, these rewards will be issued at the same time that any auto reports are generated so that the players receiving rewards are the same as those appearing at the tops of the lists.
\\

After a reward has been //added//, the following command is used to define it as a 'top player' reward:
>Command to set up: ontime rewards top <rewardID> [daily/weekly/monthly/total] <startPlace> {<endPlace>} 
\\
where:
><rewardID> = is the reward order number shown in the "/ontime rewards list" command\\
>[daily/weely/monthly/total] is the 'top list' to be used as the source for players to receive rewards\\
><startPlace> is the number (1,2,3, etc) of the player position in the list (1st, 2nd, 3rd) to receive this reward\\
><endPlace> is optional, and if used will create a range of player positions, between and including <startPlace> and <endPlace> to receive the same reward.\\
\\
In the /plugin/ontime/config.yml the administrator can enable each of the 'top reward' types (daily, weekly, etc.) independently, and they can set the day of the week //(firtsDayofWeek)// and day of the month //(firstDayofMonth)//, when the weekly and monthly rewards should be issued.  This is the same parameter used to determine when the auto-reports are to be generated.\\

Also in the config.yml the 'time period' for the issuing of rewards to the 'top players' with the highest //total// playtime should receive rewards //(totalTopReward)//, must be set by the administrator.  Based on this setting 'total top' rewards will be issued daily, weekly, or monthly.
\\
\\
===Economy Rewards Notes===
The //OnTime// plugin uses the [[http://dev.bukkit.org/server-mods/vault/|Vault ]] economy plugin, so any economy systems compatible with [[http://dev.bukkit.org/server-mods/vault/|Vault]] are therefore supported by //OnTime//. An econ reward can be further defined to be recurring, such the same reward is issued at each recurring time period.  
\\
\\
===Item Rewards Notes===
The item can be specified using the item NAME or item ID.  An item reward can also be further defined to be recurring, such the same reward is issued at each recurrent time period.  
\\
\\
If at the time that an item reward is issued to a player the player's inventory is completely full, the user will be informed of the pending reward, and the plugin will try to issue the reward again in 1 minute.  The plugin will re-try every minute until the player makes room in their inventory to receive the reward.
\\
\\
===Group  & Permission Change Rewards Notes===
The //OnTime// plugin uses the [[http://dev.bukkit.org/server-mods/vault/|Vault ]] permissions plugin, so any permission systems compatible with [[http://dev.bukkit.org/server-mods/vault/|Vault]] are therefore supported by //OnTime//. A Vault supported permission plugin is required for this //OnTime// function to be available. 
\\
\\
Group and Permission rewards are onetime events, so these cannot be defined as recurring.
\\
\\
Because there are countless permissions out there, no validity checking is done on the string entered.  So any incorrect permission specifications will not be detected by OnTime.  You will also never see any error messages from an incorrect permission spelling, so be careful.
\\
\\
For this Group Reward to work, the names of the different groups used by the system must be included in the //rewards.yml// file found in the '/plugins/ontime' directory.  It is very important that the groups be **listed in order from lowest to highest**.  The reason for this is that a player should never be automatically changed to a group which is lower than their currently assigned group.  This logic should help maintain group assignments made prior to adding OnTime to your plugin list.  The only way to add the groups to the //rewards.yml// is by editing the file directly and restarting the server.
\\
\\
There is an exception to the above rule where automated permission group change rewards must always be from a lower to higher group level.  If the time of the reward is 0 Day 0 Hour 0 Min then any group permission change will be allowed.  The purpose of this exception is to enable a group down grade for players who have been purged from the OnTime records due to inactivity, but later return to the server.  For example:
\\
\\
>New players on a your server are kept in an 'untrusted' group until they have played for six hours at which point they are upgraded to 'trusted' via an OnTime reward.  You have OnTime purging enabled such that players that have not been on for 30 days are removed from the records.  If one such player returns after being removed, you want him put back into 'untrusted' group. OnTime commands needed to set this up:

#/ontime rewards add group 0 0 0 untrusted
#/ontime rewards add group 0 6 0 trusted
#/ontime rewards exclusive add 1 trusted
\\
\\
The first command establishes the down grade reward.  The second command establishes the upgrade to trusted reward.  The third command makes the down grade (RewardID=1) exclusive to the 'trusted' group.  This last one could be optional, but it would make sure that members of other groups such as 'moderator' or 'admin', wouldn't accidentally be down graded if they happen to not have any OnTime data in the database.
\\
\\
===Command Rewards Notes===
'Reward' may not be the right term since a command could be almost anything, but I'll call 'em rewards to be consistent.  For command rewards to be available they must first be defined in the rewards.yml file under the "commands:" keyword.  The format for these definitions is:
\\
\\
**- <commandTag>:'<command> <parameter> [player] <parameter>'**
\\
\\
><commandTag> is a string identifier you create for the command.  This is the string used in the '/ontime rewards add' command to define a reward of this type.
\\
><command> is the command you want to execute.  This can be almost* any command supported by your server.
\\
><parameter> is any parameters required by the command you want to be executed
\\
>'[player]' will be replaced with the target player's when the command is executed.
\\
//I say 'almost' because if there are more variables needed other than '[player]' it may not be possible to create a working reward for some commands.//
\\
====Examples====
\\
- creative: 'creative [player]'
\\
- kill: 'kill [player]'  (Ok, not really a good reward. :-) )
\\
\\
**Please note that the (') are required and that there must be no space before or after these marks.**
\\
\\
Unlike the rest of the rewards there is no in game notice sent to the player when the command happens.  I figure that the command itself will already have appropriate messages.
\\
\\
==Other Notes==
When //OnTime// is first installed there are no default rewards established, and there is no limit to the number of levels that can be defined.  Please see the [[http://dev.bukkit.org/server-mods/ontime/pages/commands/|Command page]] for details on how to set up the system.  The rewards can also be managed by direct editing of the// rewards.yml// file found in the// /plugin/ontime// folder.  Please see the //rewards.yml// page for more information.
\\
\\
Econ, Item and command rewards can be defined as recurring.  When one is so defined, the reward will be issued at every recurrence time period, until the player reaches the time of the next defined reward.  If the last reward defined is a recurring reward, that reward will be issued at every recurrence time period forever.
\\
\\
Example: A recurring reward of $100 is defined to start at 1 day 0 hour 0 min with a recurrence time of 0 days 4 hours 0 minutes,  and a second reward of $200 is defined to happen once at 2 days 0 hours 0 min.  Once the player has been on for 1 day they will receive a $100 reward every 4 hours until they have been on the server for 2 days, at which time they will received a $200 reward.  If there are no other rewards defined after this second one, the player would never receive another reward. 
\\
\\
Similar to the 'recurring reward' designation is the 'perpetual reward' designation.  The difference between the two is that the perpetual rewards will continue to be scheduled at the repeat interval, even after the next reward time is reached.  These rewards will continue every repeat interval forever.
\\
\\
Each time a reward is added or removed in game, the rewards for all online players are automatically recalculated to take into account the changes.
\\
\\
It is possible to control what players are eligible to receive the OnTime Rewards via permissions, so this capability can be reserved for certain classes or groups already established on the server.  See the [[http://dev.bukkit.org/server-mods/ontime/pages/permissions/|permissions]] page for more information.